package nz.ac.massey.whatiscomputerscience.core.model.animator;


/**
 * Defines the functionality for classes that can be animated by an Animator
 *
 * @author Francis Stephens
 */
public interface Animatable
{
	/**
	 * Defines the possible Animator scheduling policies an Animatable Obect may have
	 * 
	 * @author Francis Stephens
	 */
	public enum SchedulingPolicy {
	/**
	 * All availiable Animators are executed simultaneously
	 * This means that each available Animator's <code>mutate( )</code> method is invoked at each animation step for the Model
	 */
	SIMULTANEOUS,
	/**
	 * All available Animators are executed one after the other
	 * This means that at any time there is at most one Animator whose <code>mutate( )</code> method is invoked at each animation step for the Model
	 */
	SEQUENTIAL,
	/**
	 * There can be at most one Animator available to the Model at any time
	 * If there is one Animator available to this Model then further Animators will be rejected
	 */
	SINGULAR};
	
	/**
	 * The act of accepting an Animator allows the Animator to mutate the state of this VectorImage
	 * VectorImages have the option of not accepting Animators for any reason
	 * In particular no animator can be effective unless it has access to a mutable image description
	 * 
	 * There exists a contract that requires that where <code>willAccept( a ) == true</code>, that <code>acceptAnimator( a )</code> will succeed
	 * This stipulation does not include run-time errors occuring in <code>acceptAnimator( a )</code>
	 * 
	 * NB: Because mutation should not occur while a vector image is being read this method must be synchronized in a threaded environment
	 * 
	 * @param animator The Animator acting upon this VectorImage
	 */
	public abstract void acceptAnimator( Animator animator );
	
	/**
	 * There exists a contract that requires that where <code>willAccept( a ) == true</code>, that <code>acceptAnimator( a )</code> will succeed
	 * This stipulation does not include run-time errors occuring in <code>acceptAnimator( a )</code>
	 * 
	 * @param animator The animator to be tested for acceptance
	 * @return Indicates whether a will be accepted by this VectorImage
	 */
	public abstract boolean willAccept( Animator animator );
	
	/**
	 * @return Indicates whether this VectorImage has any animations left to be run
	 */
	public abstract boolean animationsPending( );
}